AgentScope-Java Version

1.0.11

Description

Background

When building complex agent applications with hooks, there is currently no built-in mechanism for hooks and other components to share custom data throughout the agent execution lifecycle. For example, a PreReasoningEvent hook might need to pass contextual information (e.g., request metadata, tracing context, feature flags) to a PostActingEvent hook, but there is no standard way to do so without resorting to external state management like ThreadLocal or static maps, which are fragile in reactive/async environments.

Changes

This PR adds a getContext() method to the Agent interface, providing a mutable Map<String, Object> that is scoped to each agent instance. This allows hooks and other components to share custom data across the entire agent execution lifecycle in a thread-safe manner.

Specific changes:

• Agent.java: Added Map<String, Object> getContext() method to the interface with Javadoc.
• AgentBase.java: Added a ConcurrentHashMap-backed context field, initialized in the constructor. The getContext() method is declared final to ensure consistent behavior across all agent implementations.

Usage Example

// In a PreReasoning hook — store data
agent.getContext().put("request_id", requestId);
agent.getContext().put("start_time", System.currentTimeMillis());

// In a PostActing hook — retrieve data
String requestId = (String) agent.getContext().get("request_id");
long elapsed = System.currentTimeMillis() - (long) agent.getContext().get("start_time");

Design Decisions

• ConcurrentHashMap: Chosen for thread safety since hooks may execute on different reactor threads.
• final method: Prevents subclasses from overriding the context behavior, ensuring a single consistent implementation.
• Instance-scoped: Each agent has its own context map, avoiding cross-agent interference.

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review